package uz.rt.dicom.dictionary;


import uz.rt.dicom.ValueMultiplicity;
import uz.rt.dicom.ValueRepresentation;
import uz.rt.dicom.tag.DicomTag;

import java.util.Iterator;
import java.util.TreeMap;

/**
 * The dicom interface defines the necessary function that should be implemented in a dicom dictionary. The interface
 * enable the dicom dictionary to do the following operations:
 * <ul>
 * <li>Add an instance of the IDictionaryItem</li>
 * <ul>
 * <li>DictionaryTag</li>
 * <li>DictionarySopclassTag</li>
 * <li>DictionaryTransferSyntaxTag</li>
 * </ul>
 * <li>Iterator for all dicom items stored the dictionary</li>
 * <li>Get the value representation for a DicomTag based on the dictionary</li>
 * <li>Get the value multiplicty for a DicomTag based on the dictionary</li>
 * </ul>
 *
 * @author Tom
 * @see IDictionaryItem
 * @see DictionaryTag
 * @see DictionarySopclassTag
 * @see DictionaryTransferSyntaxTag
 */
public interface IDicomDictionary
{
// -------------------------- OTHER METHODS --------------------------

    /**
     * Add an IDictionaryItem object to the dicom dictionary.
     * Current implementation support the following IDictionaryItem implementations:
     * <ul>
     * <li>DictionaryTag</li>
     * <li>DictionarySopclassTag</li>
     * <li>DictionaryTransferSyntaxTag</li>
     * </ul>
     *
     * @param item Dictionary Item
     */
    public void add(IDictionaryItem item);

    /**
     * Add a DictionarySopclassTag to the dicom dictionary.
     *
     * @param sopclassTag Dicom dictionary Sopclass tag
     */
    public void addSopclass(DictionarySopclassTag sopclassTag);

    /**
     * Add a DictionaryTag to the dicom dictionary.
     *
     * @param tag Dicom dictionary tag
     */
    public void addTag(DictionaryTag tag);

    /**
     * Add DictionaryTransferSyntaxTag to the dicom dictionary.
     *
     * @param transferSyntaxTag Dicom dictionary transfer syntag tag
     */
    public void addTransferSyntax(DictionaryTransferSyntaxTag transferSyntaxTag);

    /**
     * Get an iterator for the DictionarySopclassTag elements stored in the dictionary.
     *
     * @return Iterator for the DictionarySopclassTag elements stored in the dictionary.
     */
    public Iterator<DictionarySopclassTag> getSopclassIterator();

    /**
     * Get all DictionarySopclassTag elements stored in the dicom dictionary.
     *
     * @return TreeMap with all DictionarySopclassTag elements
     */
    public TreeMap getSopclasses();

    /**
     * Get an iterator for the DictionaryTag elements stored in the dictionary.
     *
     * @return Iterator for the DictionaryTag elements stored in the dictionary.
     */
    public Iterator<DictionaryTag> getTagIterator();

    /**
     * Get the value multiplicity for a requested dicom tag.
     *
     * @param tag DicomTag for which the value multiplicity is queried
     * @return ValueMultiplicity instance of the requested DicomTag. Null is returned when the function argument tag
     *         is null or not present in the dictionary.
     */
    public ValueMultiplicity getTagVM(DicomTag tag);

    /**
     * Get the value representation for a requested dicom tag.
     *
     * @param tag DicomTag for which the value representation is queried
     * @return ValueRepresentation instance of the requested DicomTag. Null is returned when the function argument tag
     *         is null or not present in the dictionary.
     */
    public ValueRepresentation getTagVR(DicomTag tag);

    /**
     * Get all DictionaryTag elements stored in the dicom dictionary.
     *
     * @return TreeMap with all DictionaryTag elements
     */
    public TreeMap getTags();

    /**
     * Get an iterator for the DictionaryTransferSyntaxTag elements stored in the dictionary.
     *
     * @return Iterator for the DictionaryTransferSyntaxTag elements stored in the dictionary.
     */
    public Iterator<DictionaryTransferSyntaxTag> getTransferSyntaxIterator();

    /**
     * Get all DictionaryTransferSyntaxTag elements stored in the dicom dictionary.
     *
     * @return TreeMap with all DictionaryTransferSyntaxTag elements
     */
    public TreeMap getTransferSyntaxes();
}
